<HTML><HEAD><TITLE>test_and_setval(+VarName, ?Old, ?New)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Non-logical Variables, Arrays, Bags, Shelves and Stores</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>test_and_setval(+VarName, ?Old, ?New)</H1>
Test whether a non-logical variable has value Old and if so, set it to New.
<DL>
<DT><EM>VarName</EM></DT>
<DD>An atom
</DD>
<DT><EM>Old</EM></DT>
<DD>A term
</DD>
<DT><EM>New</EM></DT>
<DD>A term
</DD>
</DL>
<H2>Description</H2>
   VarName must be the name of a non-logical variable (not an array
   element and not a reference).  If the current value of this
   variable is not identical to Old, the predicate fails.  If it is
   identical, the variable's value gets changed to the value New. 
   Test and set is done as an atomic operation.

<H3>Modes and Determinism</H3><UL>
<LI>test_and_setval(+, ?, ?) is semidet
</UL>
<H3>Modules</H3>
This predicate is sensitive to its module context (tool predicate, see @/2).
<H3>Fail Conditions</H3>
Fails it the current value of the variable is not identical to Old
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>VarName is not ground
<DT><EM>(5) type error </EM>
<DD>VarName not an atom
<DT><EM>(5) type error </EM>
<DD>VarName is the name of a reference
<DT><EM>(41) array or global variable does not exist </EM>
<DD>VarName is not the name of a non-logical variable.
</DL>
<H2>Examples</H2>
<PRE>
Success:
     ?- setval(k, 3), test_and_setval(k, 3, 5).

     wait_for_lock :-
	    ( test_and_setval(lock, 0, 1) -&gt;
		true
	    ;
	        wait_for_lock
	    ).

Fail:
      setval(k, 1), test_and_setval(k, 3, 5).
</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/storage/decval-1.html">decval / 1</A>, <A HREF="../../kernel/storage/incval-1.html">incval / 1</A>, <A HREF="../../kernel/storage/variable-1.html">variable / 1</A>, <A HREF="../../kernel/storage/setval-2.html">setval / 2</A>, <A HREF="../../kernel/storage/getval-2.html">getval / 2</A>
</BODY></HTML>
